home *** CD-ROM | disk | FTP | other *** search
/ The PC-SIG Library 10 / The PC-Sig Library - Shareware for the IBM PC and Compatibles (PC-SIG)(Tenth Edition Disks 1-2804)(1991).iso / PC_SIGCD / 27 / 2 / DISK2727.ZIP / NEW2MAKE.TXT < prev    next >
Text File  |  1991-05-27  |  11KB  |  275 lines
  1. ****************************************************************************
  2. ****************************************************************************
  3.                               NEW2MAKE.TXT
  4.           For Programmers Who Are New To Using Make Programs
  5. ****************************************************************************
  6. ****************************************************************************
  7.  
  8.  
  9. If you are new to make programs reading this file before reading the manual 
  10. or using SUPER-MAINT should be helpful.  Program maintenance can seem 
  11. complicated, but once you begin using a make utility it can be a real time 
  12. saver.
  13.  
  14. ****************************************************************************
  15. WHAT IS A MAKE UTILITY?
  16.  
  17. Make utilities are normally used to build programs out of multiple source 
  18. code files.  Let's use the SUPER-MAINT  sample program as an example.  It 
  19. is written in three source code files:  SAMPLE.C, SAMPLE1.C, and SAMPLE2.C.
  20. To compile and link these from the command line we need to do it in four 
  21. steps:
  22.  
  23.                          compile SAMPLE.C
  24.                          compile SAMPLE1.C
  25.                          compile SAMPLE2.C
  26.                          link the 3 modules together
  27.  
  28. A make utility turns this into a one step process.  All of the instructions 
  29. for building your program are written into a text file called a `make file.'
  30. When you call the maker with the make file it goes down the list of 
  31. instructions, performing each as it goes along.
  32.  
  33. The above paragraph could just as easily describe batch files.  What 
  34. distinguishes make utilities is that each instruction is only carried out if 
  35. an IF:THEN condition is met.  This condition always has to do with the age of 
  36. the files you use to build your program.  Consider the first command:
  37.  
  38.                          compile SAMPLE.C
  39.  
  40. In a make file this would look like this:
  41.  
  42.                          SAMPLE.OBJ: SAMPLE.C
  43.                                  compile SAMPLE.C
  44.  
  45. The command is saying, "If SAMPLE.C is newer than SAMPLE.OBJ, then compile 
  46. SAMPLE.C.  If the age of the files is the same do nothing."  If you are 
  47. working on a big project this saves time, because the maker automatically 
  48. knows only to compile the parts of your program that have changed since the 
  49. last time you built it.  (Compiling and linking the SUPER-MAINT Editor took 
  50. about 15 minutes on a 386 machine.  Most builds using SUPER-MAINT only took 
  51. a minute or two, because ONLY THE NEW MODULES HAD TO BE COMPILED.)
  52.  
  53. The link command would look like this:
  54.  
  55.                          SAMPLE.EXE: SAMPLE.OBJ SAMPLE1.OBJ SAMPLE2.OBJ
  56.                                  link SAMPLE.EXE
  57.  
  58. It is saying, "If SAMPLE.OBJ, SAMPLE1.OBJ, or SAMPLE2.OBJ is newer than 
  59. SAMPLE.EXE, then link the program."  As you can see there can be multiple 
  60. dependencies.  In make file jargon a "target" is the file you are building 
  61. (SAMPLE.EXE), and a "dependent" is the file or files that must be newer 
  62. than the target if the target is to be built (the .OBJ files listed after 
  63. the colon).
  64.  
  65. Here is what the whole make file would look like:
  66.  
  67.                          SAMPLE.OBJ: SAMPLE.C
  68.                                  compile SAMPLE.C
  69.  
  70.                          SAMPLE1.OBJ: SAMPLE1.C
  71.                                  compile SAMPLE1.C
  72.  
  73.                          SAMPLE2.OBJ: SAMPLE2.C
  74.                                  compile SAMPLE2.C
  75.  
  76.                          SAMPLE.EXE: SAMPLE.OBJ SAMPLE1.OBJ SAMPLE2.OBJ
  77.                                  link SAMPLE.EXE
  78.  
  79.  
  80.  
  81.  
  82. ****************************************************************************
  83. HOW ARE MACROS USED?
  84.  
  85. Like many programs, make utilities can use macros (a set of commands that 
  86. have been assigned to one short command).  Let's say you want to include 
  87. debugging information in your program.  Your compiler has special flags 
  88. that you call it with to include this information for the debugger.  You 
  89. could build a macro with these flags, and another that you would use for 
  90. building your program after it has been debugged.
  91.  
  92. DEBUG = flags to build with debugging info
  93. NODEBUG = flags to use for the final program build.
  94.  
  95. Now to include the debugging flags you could use this command in your make 
  96. file:
  97.  
  98.                          SAMPLE.OBJ: SAMPLE.C
  99.                                  compile $(DEBUG) SAMPLE.C
  100.  
  101. To use the flags for a finished program you would use:
  102.  
  103.                          SAMPLE.OBJ: SAMPLE.C
  104.                                  compile $(NODEBUG) SAMPLE.C
  105.  
  106. ****************************************************************************
  107. WHY IS SUPER-MAINT EASIER?
  108.  
  109. Programmer's SUPER-MAINT is easier than most other makers because:
  110.  
  111. 1.  It builds your make file for you, and other useful files like response 
  112.     files for your linker.
  113.  
  114. 2.  It makes use of macros.  Specific macros can be called with simple 
  115.     command line flags so you don't have to remember macro names or 
  116.     complicated commands.
  117.  
  118. 3.  Once you have called the maker from the command line it remembers which 
  119.     flags you called it with and which make file you called.  You don't have 
  120.     to re-enter this information unless you are changing some of it.  Thus, 
  121.     if you are building three programs with all the same parameters you would 
  122.     type:
  123.  
  124.                                sm -3 -d prog 1
  125.                                sm prog2
  126.                                sm prog3
  127.  
  128.     (You don't have to re-enter the `-3 -d' flags).
  129.  
  130. ****************************************************************************
  131. WHAT IS A RESPONSE FILE?
  132.  
  133. Some programs ask you questions about what you want them to do as they go 
  134. along.  Some examples are linkers, librarians and assemblers.  Each time one 
  135. of these programs needs more information from you it stops to ask for it.
  136.  
  137. A response file automates the process.  You provide the answers to the 
  138. questions in advance, and tell the program to look for the answers in the 
  139. response file.  This way it can do its job without stopping to bother you.
  140.  
  141. A linker needs to know such things as what files to link, what to call the 
  142. executable file (the finished program), what to call the map file, the names 
  143. of the libraries you want to link into your program, and so on.  An example 
  144. might look like this:
  145.  
  146.                          sample.obj+
  147.                          sample1.obj+
  148.                          sample2.obj
  149.                          sample.exe
  150.                          sample.map
  151.                          mylib1+
  152.                          mylib2
  153.  
  154. Notice the plus signs.  These tell the linker there are more object files 
  155. or libraries to link.  Different linkers (and other programs) use various 
  156. methods and symbols (& instead of +, for example), depending on what 
  157. questions the program asks and the order it asks them in.  See your compiler 
  158. manual for the appropriate response file format for your language.
  159.  
  160. ****************************************************************************
  161. SOME NOTES ABOUT HOW SUPER-MAINT DOES WHAT IT DOES
  162.  
  163. If you want to build your own make files you may do so.  You can use 
  164. SUPER-MAINT macro sets (if so you must use a whole set), or not, as you 
  165. choose.  You may also define your own macros for use with the macro sets, 
  166. or by themselves.
  167.  
  168. **********
  169. THE MACROS
  170.  
  171. SUPER-MAINT makes the business of building a program easier by keeping 
  172. commands in sets of macros.  Depending on the flags you use at the command 
  173. line, only certain macros are called by SM.EXE (the maker).  SUPER-MAINT 
  174. macros, when put together, comprise the command line for your compiler (or 
  175. linker, etc.).
  176.  
  177. Let's use the following macro set for an example:
  178.  
  179. L1C0 = -c
  180. L1M1 = /AS
  181. L1M2 = /AM
  182. L1M3 = /AL
  183. L1ND =
  184. L1D = /Zi /Od
  185. L1F1 = /W4
  186. L1F2 = /Os /Zr
  187.  
  188. For each language you use (C, Assembler, etc) SUPER-MAINT needs a full set 
  189. of macros.  Notice that one of the macros in the example is empty.  It must 
  190. be part of the set, even if you don't assign any value to it.
  191.  
  192. Not all the macros are used each time you call SM.EXE.  However, the macros 
  193. that ARE used are always called in the same order, from top to bottom.
  194.  
  195. These macros are ALWAYS called:
  196.  
  197. xxCO      the flag for the compiler to compile without calling the linker
  198. xxF1      any miscellaneous flags you want
  199. xxF2      same as xxF1 (when set for Borland languages this is called AFTER
  200.           the name of the file to compile
  201.  
  202. Only one of these macros is called:
  203.  
  204. xxM1      the flag for the first memory model
  205. xxM2      the flag for the second memory model
  206. xxM3      the flag for the third memory model
  207.  
  208. You define up to three memory models.  The compiler flags for those models 
  209. are stored in the above macros.
  210.  
  211. Only one of these macros is called:
  212.  
  213. xxND      the flags used for a final program build
  214. xxD       the flags needed to include debugging information in your program
  215.  
  216. SO!  If you called SUPER-MAINT at the command line:
  217.  
  218.                  sm -1 -n sample
  219.  
  220. it would call your compiler like so:
  221.  
  222.               cl /c /AS /W4 /Os /Zr sample.c
  223.  
  224. OR if your called SUPER-MAINT:
  225.  
  226.                  sm -3 -d sample
  227. it would compile:
  228.  
  229.               cl /c /AL /Zi /Od /W4 /Os /Zr sample.c
  230.  
  231. Notice that for each example, the macros that are used are called in the same 
  232. order.
  233.  
  234. ******************************
  235. USING SME.EXE TO AUTOMATE THIS
  236.  
  237. SME has two areas to keep your macro set information: a permanent area 
  238. (language definition files), and a temporary area (LASTMACS.SM).
  239.  
  240. Language Definition Files:
  241.  
  242. There are five language definition files.  Three are for programming 
  243. languages, one is for the linker and one for the librarian.  if you don't 
  244. use all of these you may have blank "lang def" files.  You keep permanent 
  245. information, including compiler flags you ALWAYS use, in the lang def files.  
  246. You can edit these files using the "Toolbox" "Lang Def Files" choices in 
  247. SME.EXE.
  248.  
  249. LASTMACS.SM:
  250.  
  251. Information that is used for your current project is kept in a file called 
  252. LASTMACS.SM.  You get to this file using the "Make" "Macros" choices in 
  253. SME.EXE.  Usually you will start with the permanent settings in your lang def 
  254. files.  You use alt-r to get these settings.  Then you can press alt-e to edit 
  255. each macro, adding special flags as needed.  For example, if you are editing 
  256. the linker macros you may want to add a stack size command.
  257.  
  258. ****************************
  259. RESPONSE FILES AND LIBRARIES
  260.  
  261. If you are building your make files with SME.EXE SUPER-MAINT requires that 
  262. your linker (or librarian) use a response file.  
  263.  
  264. SME.EXE will build the response file automatically from the information you 
  265. set up in SMSET.EXE (the setup facility.  This can be accessed from the 
  266. "Setup" menu in SME.EXE).  It is particularly important to set up your 
  267. library names prior to building a response file.  
  268.  
  269. The libraries are called in the order you list them.  So if your language 
  270. requires libraries to be linked in a certain order you should list them in 
  271. that order.
  272.  
  273. Also, some brands require you to list the full path of the library.  Refer to 
  274. your compiler manual to see if you have to do this.
  275.